home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / f90 / ran.z / ran
Encoding:
Text File  |  2002-10-03  |  9.0 KB  |  217 lines
  1. RAN(3I)                                               Last changed: 4-13-99
  2.  
  3.  
  4. NNAAMMEE
  5.      __rraannff, RRAANNFF, RRAANNGGEETT, RRAANNSSEETT - Computes pseudo-random numbers
  6.  
  7. SSYYNNOOPPSSIISS
  8.      C/C++:
  9.  
  10.      ##iinncclluuddee <<iinnttrriinnssiiccss..hh>>
  11.      ddoouubbllee __rraannff((vvooiidd));;
  12.  
  13.      Fortran:
  14.  
  15.      RRAANNFF(())
  16.  
  17.      RRAANNGGEETT (([II==]_i))
  18.  
  19.      RRAANNSSEETT (([KK==]_k))
  20.  
  21.      Fortran on UNICOS/mk systems only:
  22.  
  23.      RRAANNSSEETT (([KK==]_k [,, [JJ==]_j]))
  24.  
  25. IIMMPPLLEEMMEENNTTAATTIIOONN
  26.      C/C++:  UNICOS and UNICOS/mk systems
  27.  
  28.      Fortran:  UNICOS, UNICOS/mk, IRIX systems
  29.  
  30.      Cray C/C++, CF90, MIPSpro 7 Fortran 90
  31.  
  32. SSTTAANNDDAARRDDSS
  33.      C/C++ extension
  34.  
  35.      Fortran extension
  36.  
  37. DDEESSCCRRIIPPTTIIOONN
  38.      The __rraannff and RRAANNDD functions return a pseudo-random floating-point
  39.      number in the range of 0.0 < _x < 1.0.
  40.  
  41.      The RRAANNGGEETT intrinsic procedure returns a seed from the random number
  42.      seed table.
  43.  
  44.      The RRAANNSSEETT function establishes a seed in the random number seed
  45.      table.
  46.  
  47. NNOOTTEESS
  48.    CC//CC++++
  49.      Because __rraannff is an intrinsic function, no externally visible library
  50.      function is available for it.
  51.  
  52.    FFoorrttrraann
  53.      RRAANNFF obtains the first or next in a series of pseudo-random numbers.
  54.      Parenthesis are required, that is:  _v_a_r == RRAANNFF(()).  If an argument is
  55.      supplied, it is ignored.
  56.  
  57.      The RRAANNGGEETT intrinsic function obtains a seed.  It can be called as a
  58.      function or a subroutine; it is recommended that this routine be used
  59.      as a function because it is not considered intrinsic when called as a
  60.      subroutine.  RRAANNGGEETT has an optional integer argument.  If present, the
  61.      argument is set to the seed.  The argument for RRAANNGGEETT is as follows:
  62.  
  63.      _i    An integer of default kind (KKIINNDD==88).  If present, RRAANNGGEETT returns
  64.           the seed in _i.
  65.  
  66.      On UNICOS and UNICOS/mk systems, the RRAANNSSEETT intrinsic function
  67.      establishes a seed by using the lower 48 bits of the argument.  The
  68.      result type is typeless.  If no argument or a zero argument is
  69.      supplied, the seed is reset to an initial default value.  When the
  70.      seed of the random number generator is reset, RRAANNSSEETT does not store
  71.      the supplied argument as the first value in the buffer of the random
  72.      number seeds.  If an argument is supplied, the lower 48 bits are used
  73.      as the random-number seed.  The rightmost bit is always set to 1.
  74.  
  75.      The RRAANNSSEETT arguments are as follows:
  76.  
  77.      _k    An optional integer, real, or Boolean argument of default kind
  78.           (KKIINNDD==88) The range of argument _k is |_k| < _i_n_f, where _i_n_f is as
  79.           follows:
  80.                                                            2450
  81.           * On UNICOS systems, infinity is approximately 10    .
  82.                                                                        308
  83.           * On UNICOS/mk and IRIX systems, infinity is approximately 10   .
  84.  
  85.      _j    An optional integer argument that, if specified, is used as a
  86.           count for skipping the first section of sequential random
  87.           numbers.  You can use this to create a complete sequence of
  88.           random numbers while running on many PEs by breaking up the
  89.           sequence into subsequences and using RRAANNSSEETT() to get each
  90.           subsequence started in the correct location.
  91.  
  92.      The names of these intrinsics cannot be passed as arguments.
  93.  
  94.    TThhee RRAANNFF AAllggoorriitthhmm
  95.      In Fortran on CRAY C90 systems, the random number generation algorithm
  96.      uses the following two equations:
  97.  
  98.      * SS((_n++11)) == MM11**SS((_n)) mmoodd 22****4488
  99.  
  100.      * SS((_n++6644)) == MM6644**SS((_n)) mmoodd 22****4488
  101.  
  102.      Each SS((_i)) is the _ith seed.
  103.  
  104.      The first equation is used to generate the first 128 random numbers
  105.      and store them in a table if a call to RRAANNSSEETT() was done.  Otherwise,
  106.      the table contains the first 128 random numbers from the default seed.
  107.      The second equation is used because it vectorizes.
  108.  
  109.      The default seed is SS((00)) == 11227744332211447777441133115555 (octal).
  110.  
  111.      The operations MM11**SS((_n)) and MM6644**SS((_n)) are done as integer
  112.      multiplications in such a way to preserve the lower 48 bits.  It is
  113.      the lower 48 bits that make the next random number seed and are used
  114.      in the return value.
  115.  
  116.      The return value (random number) is the newly generated seed with an
  117.      exponent of 40000 (octal) added.  This is normalized before exit.
  118.  
  119.      The multiplier MM11 is 11220077226644227711773300556655 (octal) and is related to MM6644 by
  120.      the following expression:
  121.      MM6644 = lower 48 bits of MM11****6644 == 77002277442233334466112255440011 (octal).
  122.  
  123.      For example, the following Fortran program, when compiled with the
  124.      ff9900 --ii 6644 option on a CRAY C90 system, is the equivalent of the RRAANNFF
  125.      function:
  126.  
  127.              cc
  128.              c     THIS IS A FORTRAN VERSION OF RANF() FUNCTION
  129.              cc
  130.                    REAL FUNCTION RANF()
  131.                    REAL NORM
  132.                    INTEGER MHI,MLO,EXPO,SEED,SEEDHI,SEEDLO
  133.                    DATA SEED/1274321477413155B/
  134.                    SAVE SEED
  135.  
  136.                    MHI = 12072642B
  137.                    MLO = 71730565B
  138.  
  139.                    EXPO = SHIFTL(40000B,48)
  140.  
  141.                    SEEDHI = SHIFTR(AND(SHIFTL(77777777B,24),SEED),24)
  142.                    SEEDLO = AND(77777777B,SEED)
  143.  
  144.                    SEED = AND(7777777777777777B,SEEDLO*MLO+
  145.                   1           SHIFTL(SEEDLO*MHI+SEEDHI*MLO,24))
  146.  
  147.                    RANF=NORM(OR(EXPO,SEED),0.0)
  148.                    RETURN
  149.                    END
  150.              cc
  151.              c     THIS IS HERE TO NORMALIZE THE FLOATING POINT RESULT
  152.              cc
  153.                    REAL FUNCTION NORM(X,Y)
  154.                    REAL X,Y
  155.                    NORM = X+Y
  156.                    RETURN
  157.                    END
  158.  
  159.      On IRIX systems, RRAANNFF uses a 64-bit linear congruential generator with
  160.      a default seed of 1274321477413155 (octal).
  161.  
  162.    TThhee RRAANNFF RReeppeeaatt PPeerriioodd
  163.      In Fortran, the period of RRAANNFF(()) is 2**46.  If you need to insure that
  164.      two random number ranges do not overlap, you can determine this
  165.      empirically by generating the two sets of numbers and comparing them
  166.      against one another, and also against themselves, for an overlap.  It
  167.      should be noted, however, that when using RRAANNSSEETT to set the random
  168.      number seed, the algorithm used always rounds up even-numbered seeds
  169.      to the nearest odd-numbered seed (that is, the right most bit is
  170.      always set to one).  Some adjacent pairs of seeds will generate
  171.      exactly the same set of random numbers.  For example, seeds 4 and 5
  172.      will generate the same set of random numbers.
  173.  
  174.    RRAANNFF aanndd MMuullttiittaasskkiinngg
  175.      In Fortran, the random number generator uses static memory storage for
  176.      the random number seed table, so the RRAANNFF, RRAANNSSEETT, and RRAANNGGEETT
  177.      functions must be protected (locked) when called from a multitasked
  178.      program.
  179.  
  180.      RRAANNFF generates a set of random numbers such that each random number
  181.      depends on the previous random number for its value.  Thus, depending
  182.      on the order in which the tasks calling RRAANNFF execute, a different set
  183.      of random numbers will be returned to each task.  It cannot be
  184.      guaranteed that each task will get a distinct and reproducible set of
  185.      random number values.
  186.  
  187. RREETTUURRNN VVAALLUUEESS
  188.      __rraannff and RRAANNFF return a 64-bit floating-point number in the range
  189.      0.0 < _x < 1.0.
  190.  
  191.      RRAANNGGEETT returns a 64-bit integer result.
  192.  
  193.      RRAANNSSEETT returns a 64-bit typeless result.
  194.  
  195. EEXXAAMMPPLLEESS
  196.      The following examples are written in Fortran:
  197.  
  198.                DO 10 I=1,10
  199.           10   RANDOM(I)=RANF()
  200.  
  201.  
  202.                _i_s_e_e_d=RANGET(_i_v_a_l_u_e)
  203.  
  204.  
  205.                _d_u_m_m_y=RANSET(_i_v_a_l_u_e)
  206.  
  207. SSEEEE AALLSSOO
  208.      RRAANNDDOOMM__NNUUMMBBEERR(3I), RRAANNDDOOMM__SSEEEEDD(3I)
  209.  
  210.      rraanndd(3C) in the _U_N_I_C_O_S _S_y_s_t_e_m _L_i_b_r_a_r_i_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l
  211.  
  212.      A complete list of C/C++ intrinsic functions available on UNICOS and
  213.      UNICOS/mk systems is in the _C_r_a_y _C/_C++ _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l.
  214.  
  215.      _I_n_t_r_i_n_s_i_c _P_r_o_c_e_d_u_r_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l for the printed version of this
  216.      man page.
  217.